.TH lha_monitor 1 "1 May 2012" "TrueCL Commands"

.SH NAME
lha_monitor \- Manage Application and Node Monitoring

.SH SYNOPSES
Application monitor options:
.TS
l l.
lha_monitor --list	\fB--type\fP \fIa\fP \fB--application\fP \fIA\fP [\fB--force\fP]
lha_monitor --get	\fB--type\fP \fIa\fP \fB--application\fP \fIA\fP \fB--name\fP \fIX\fP \fB--file\fP \fIF\fP [\fB--force\fP]
lha_monitor --set	\fB--type\fP \fIa\fP \fB--application\fP \fIA\fP \fB--name\fP \fIX\fP \fB--file\fP \fIF\fP [\fB--force\fP]
lha_monitor --delete	\fB--type\fP \fIa\fP \fB--application\fP \fIA\fP \fB--name\fP \fIX\fP [\fB--force\fP]
lha_monitor --template	\fB--type\fP \fIa\fP \fB--file\fP \fIF\fP
.TE

Node related monitor changes:
.TS
l l.
lha_monitor --list	\fB--type\fP \fIn\fP \fB--node\fP \fIN\fP
lha_monitor --get	\fB--type\fP \fIn\fP \fB--node\fP \fIN\fP \fB--name\fP \fIX\fP \fB--file\fP \fIF\fP
lha_monitor --set	\fB--type\fP \fIn\fP \fB--node\fP \fIN\fP \fB--name\fP \fIX\fP \fB--file\fP \fIF\fP
lha_monitor --delete	\fB--type\fP \fIn\fP \fB--node\fP \fIN\fP \fB--name\fP \fIX\fP
lha_monitor --template	\fB--type\fP \fIn\fP \fB--file\fP \fIF\fP
.TE

.SH DESCRIPTION
The \fIlha_monitor(1)\fP command is used to list, add, edit and delete monitors for either a particular node or a particular application. The two monitor types are distinctly different:

.TP 8
* Application
These are monitors that are run only when the particular application is running as part of the cluster. Obviously this monitoring will take place on the node where the application is currently running.
.TP
* Node
This is a check which is run whenever the node is running as part of the cluster and is used to check the health of the node itself, rather than a particular application that the node might currently be running.
.RE

The architecture for handling monitoring is extensible; though at present the
only monitors available as listed in the following table:

.TS
l l l.
=
Name	Node/App	Purpose
=
dummy	Application	A dummy application monitor to be used as a
		user framework for coding site specific
		application monitors.
dummy	Node	A dummy node monitor to be used as a
		template for coding site specific
		node monitors.
process	Application	Allows a regular expression to determine
		whether one or more processes related to
		an application are currently running.
proc_count	Node	Checks the number of processes currently
		running on the node in question.
swap_space	Node	Returns a percentage of swap space
		used on the node in question.
tcp_sockets	Node	A count of the number of 
		established socket connections.
fs_space	Node	A percentage of space used in a specified
		file system.
.TE

The utility relies on specification of a check via XML files. To make this
process a little easier it is possible to extract an example template to
use rather than starting from nothing.

.SH ARGUMENTS
.TP 8
--name
Used to define a label for this monitor. \fBAll monitors names must be unique
across the cluster.\fP Since there is no limit to name lengths it is 
prudent to use a naming scheme such as 'appname.monitor_name' or 
\'nodename.monitor_name' for example.
.TP
--type
Used to indicate the type of monitor that is the target of this command.
It should be 'a' for application or 'n' for node.
.TP
--file
Indicates the name of a local file that should be written to (in the case
of the \fB--get\fP or \fB--template\fP actions), or read from (in the case
of the \fB--put\fP action).
.TP
--force
Force the action to occur. If an application monitor is to be modified or 
removed then all nodes that host that application must normally be up and
available. Use this argument to allow changes (and database inconsistencies)
if one or more of those nodes are not available.
.TP
--node
Used to indicate the node that is being queried, modified, etc.
.TP
--application
Used to indicate the application that is being queried, modified, etc.
.TP
--list
This is used to list the currently configured monitors for the application
specified, or the node specified. 
.TP
--all
This is typically used with the \fB--list\fP action and will list all monitors 
in the cluster as a whole or relevant to a specified node or application.

.SH FILE FORMAT
The XML file format is not particularly complex; particularly considering the
use of the \fB--template\fP option to retrieve a sample one that can be 
modified as necessary.

A sample node monitor XML definition file might look similar to:
.TS
l.
<?xml version="1.0" standalone="yes"?>
<node_monitoring_configuration>
  <monitor name="swap" type="swap_space" interval="5 mins">
  <!-- 
    Each entry has a single "monitor" element. 
    The monitor has the following attributes:
    name      The user assigned name of the monitor.
    type      The monitor type, such as dummy or process.
    interval  How often to run the check in question.
  -->
    <instance days="all" from="08:00" to="17:00" rearm="5 mins">
      <!--  
        Each monitor might have several "instance" elements, 
        which can include the following attributes [all optional]:
        days   Days to perform the associated actions.
        from   The times between which the actions should match.
        to      
        rearm  The time after which if no other failures occur the
               monitor failure count is reset to 0.
      -->
      <action threshold="95%" todo="send_alert,move_apps"/>
      <!--  At least one action line should be present. These determine which
        actions to take depending on the current status of the monitor.
        occurrence_minmax What to run for this range of failure
                          numbers [optional].
        threshold   If the action is based on a value rather
                    than a number of failures [optional].
        todo        The actions to run, comma separated.
      -->
    </instance>
    <instance rearm="30 mins">
      <action threshold="80%" todo="send_alert,move_one_app"/>
    </instance>
  </monitor>
 </node_monitoring_configuration>
.TE

A sample application monitor XML definition file might look similar to:

.TS
l.
<?xml version="1.0" standalone="yes"?>
<application_monitoring_configuration>
  <!-- 
    Each entry has a single "monitor" element.
    The monitor has the following attributes:
    name      The user assigned name of the monitor.
    type      The monitor type, such as dummy or process.
    interval  How often to run the check in question.
    value     What to search for.
  -->
  <monitor name="pidmonitor" type="process" interval="10 secs"
    value="procstring"> <instance days="all" from="08:00" to="17:00"
    rearm="30 mins">
      <!--
        Each monitor might have several "instance" elements, 
        which can include the following attributes [all optional]:
        days   Days to perform the associated actions.
        from   The times between which the actions should match.
        to      
        rearm  The time after which if no other failures occur the
               monitor failure count is reset to 0.
      -->
      <action occurrence_minmax="1,3" todo="script:/app/restart"/>
      <!--  At least one action line should be present. These determine which
        actions to take depending on the current status of the monitor.
        occurrence_minmax What to run for this range of failure
                          numbers [optional].
        threshold         If the action is based on a value rather
                          than a number of failures [optional].
        todo              The actions to run, comma separated.
      -->
      <action occurrence_minmax="4,9999" todo="send_alert,move_app"/>
    </instance>
    <instance rearm="1 hour">
      <action occurrence_minmax="1,3" todo="script:/app/restart"/>
      <action occurrence_minmax="4,9999" todo="send_alert,move_app"/>
    </instance>
  </monitor>
</application_monitoring_configuration>
.TE

.SH EXIT CODES
If the action is question is successful a '0' will be returned. Any other
value indicates failure.

.SH AUTHOR
The TrueCL software was written by Simon Edwards, (C) 2006-2012, working
for Advantsys Computer Services Ltd - www.advantsys.co.uk.

.SH SEE ALSO
.BR lha_event(1),
.BR lha_netd(1),
.BR lha_stat(1),

.SH AVAILABILITY
This utility was specifically written under the GNU GPL license and as required
by such software comes with \fIno warranty or guarantee of any kind\fP. For
more information, please see the following page: truecl.advantsys.co.uk.

